<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: howl.config</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <script src="https://code.jquery.com/jquery-1.12.3.min.js" type="text/javascript"></script>
    <script src="/javascripts/bootstrap.min.js" type="text/javascript"></script>
    
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_api doc_api_config'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../'>Howl 0.4 Documentation</a></li><li>Api</li><li>howl.config</li></ol>
      <h1 id="howl.config">howl.config</h1>    <div class="toc">
      <div class="toc-title">
        <span>howl.config</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#overview" class="toc-group-header overview">Overview</a>
</div>
<div class="toc-group">
<a href="#properties" class="toc-group-header properties">Properties</a>
<li class=""><a href="#definitions">definitions</a></li>
</div>
<div class="toc-group">
<a href="#functions" class="toc-group-header functions">Functions</a>
<li class=""><a href="#define">define </a></li>
<li class=""><a href="#get">get </a></li>
<li class=""><a href="#local_proxy">local_proxy </a></li>
<li class=""><a href="#set">set </a></li>
<li class=""><a href="#watch">watch </a></li>
</div>
</div>
</div>
&#x000A;&#x000A;<h2 id="overview">Overview</h2>&#x000A;&#x000A;<p>Things that are meant to be configurable in Howl are exposed as &ldquo;configuration&#x000A;variables&rdquo;. Configuration variables can be set either interactively from within&#x000A;Howl, using the <code>set</code> command, or programmatically from code. To get an overview&#x000A;of currently available variables, type <code>set</code> and press <code>space</code> at the readline&#x000A;to view a list.</p>&#x000A;&#x000A;<p>Configuration variables can be specified at three different levels in Howl,&#x000A;in ascending order of priority:</p>&#x000A;&#x000A;<ul>&#x000A;<li><em>Globally</em></li>&#x000A;</ul>&#x000A;&#x000A;<p>The value set for the variable is used unless overridden by a mode or buffer&#x000A;specific setting (the <code>set</code> command always sets variables globally).</p>&#x000A;&#x000A;<ul>&#x000A;<li><em>Per mode</em></li>&#x000A;</ul>&#x000A;&#x000A;<p>The value is set for a particular mode (e.g. &ldquo;Lua&rdquo; or &ldquo;Ruby&rdquo;), and is applied&#x000A;whenever a buffer with that particular mode is active. The value is used unless&#x000A;overridden by a buffer specific setting, and overrides any global setting.</p>&#x000A;&#x000A;<ul>&#x000A;<li><em>Per buffer</em></li>&#x000A;</ul>&#x000A;&#x000A;<p>The value is set for a particular buffer, and is applied whenever that buffer is&#x000A;active. The value overrides any mode specific or global setting.</p>&#x000A;&#x000A;<p>As described above, variables can be set on three different levels. No matter&#x000A;the on what level they&rsquo;re set, they&rsquo;re always set (and accessed) using <code>config</code>&#x000A;objects. For global accesses, you would use <code>howl.config</code> (this module). For&#x000A;mode variables you access variables using the config object on a particular mode&#x000A;instance, and similarly for buffer variables you use the config object for a&#x000A;particular buffer.</p>&#x000A;&#x000A;<p>The following code snippet illustrates the idiomatic ways of setting variables&#x000A;on different levels:</p>&#x000A;<pre class="highlight lua"><span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">my_var</span> <span class="o">=</span> <span class="s1">'foo'</span>&#x000A;<span class="n">howl</span><span class="p">.</span><span class="n">mode</span><span class="p">.</span><span class="n">by_name</span><span class="p">(</span><span class="s1">'ruby'</span><span class="p">).</span><span class="n">config</span><span class="p">.</span><span class="n">my_var</span> <span class="o">=</span> <span class="s1">'foo'</span>&#x000A;<span class="n">howl</span><span class="p">.</span><span class="n">app</span><span class="p">:</span><span class="n">new_buffer</span><span class="p">().</span><span class="n">config</span><span class="p">.</span><span class="n">my_var</span> <span class="o">=</span> <span class="s1">'foo'</span>&#x000A;</pre>&#x000A;<p><em>See also</em>:</p>&#x000A;&#x000A;<ul>&#x000A;<li>The <a href="../spec/config_spec.html">spec</a> for config</li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="properties">Properties</h2>&#x000A;&#x000A;<h3 id="definitions">definitions</h3>&#x000A;&#x000A;<p>A table of all known variables definitions, keyed by the variable name. For more&#x000A;information about the structure of the definitions, see <a href="#define">define</a>.</p>&#x000A;&#x000A;<h2 id="functions">Functions</h2>&#x000A;&#x000A;<h3 id="define">define <span class="arg-list">(options)</span></h3>&#x000A;&#x000A;<p>Defines a new config variable. Options can contain the following fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><p><code>name</code>: The name of the configuration variable (<em>required</em>)</p></li>&#x000A;<li><p><code>description</code>: A description of the configuration variable (<em>required</em>)</p></li>&#x000A;<li><p><code>scope</code>: An optional value specifying the scope of the variable. One of&#x000A;<code>local</code> and <code>global</code>. Local variables are only allowed to be set for a&#x000A;<a href="buffer.html">Buffer</a> or a <a href="mode.html">mode</a>, whereas a global variable can only be directly on&#x000A;the global config.</p></li>&#x000A;<li><p><code>validate</code>: A function that will be used for validating any values set&#x000A;for this variable. Whenever a value is set for the variable, this function&#x000A;will be invoked with the new value as sole parameter. The function should&#x000A;return true if the value is valid, and false otherwise.</p></li>&#x000A;<li><p><code>convert</code>: A function that will be used for converting a value into a type&#x000A;suitable for the variable. Whenever a value is set for the variable, this function&#x000A;will be invoked with the new value as sole parameter, and the return value,&#x000A;if not nil, will be used as the value. Keep in mind that variables are set not&#x000A;only via code, but also interactively through commands. In the latter case, values&#x000A;will invariably be strings.</p></li>&#x000A;<li><p><code>tostring</code>: A function that will be used for transforming a value into a&#x000A;string representation suitable for displaying. This would typically be used for&#x000A;more advanced option types. For symmetry it&rsquo;s recommended that any <code>convert</code>&#x000A;function is able to successfully convert the return value of <code>tostring</code> back&#x000A;into a native representation.</p></li>&#x000A;<li><p><code>options</code>: A list (table) of valid values for the variable. Any set value will&#x000A;be validated to be part of this list (after conversion), if set.</p></li>&#x000A;<li><p><code>type_of</code>: To simplify defining new variables in Howl, there are a set&#x000A;of predefined types you can use that will handle validation, conversion,&#x000A;etc. of variable values for you. You use one of these by specifying the&#x000A;name of the predefined type here (as a string). Currently predefined&#x000A;types are:</p>&#x000A;&#x000A;<ul>&#x000A;<li>boolean</li>&#x000A;<li>number</li>&#x000A;<li>string</li>&#x000A;<li>string_list</li>&#x000A;</ul></li>&#x000A;</ul>&#x000A;&#x000A;<h3 id="get">get <span class="arg-list">(name)</span></h3>&#x000A;&#x000A;<p>Gets the global value of the variable named <code>name</code>. While getting the value of a&#x000A;variable using <code>get</code> is perfectly fine, note that the idiomatic way of getting&#x000A;variables values globally is to just to index the config module, like so:</p>&#x000A;<pre class="highlight lua"><span class="kd">local</span> <span class="n">val</span> <span class="o">=</span> <span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">my_variable</span>&#x000A;</pre>&#x000A;<h3 id="local_proxy">local_proxy <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Returns a new configuration proxy object. A proxy object offers access to all&#x000A;configuration variables defined in Howl, using simple indexing:</p>&#x000A;<pre class="highlight lua"><span class="n">proxy</span> <span class="o">=</span> <span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">local_proxy</span><span class="p">()</span>&#x000A;<span class="n">proxy</span><span class="p">.</span><span class="n">indent</span> <span class="c1">-- =&gt; 2</span>&#x000A;</pre>&#x000A;<p>Assigning to a proxy object only sets the value locally however:</p>&#x000A;<pre class="highlight lua"><span class="n">proxy</span> <span class="o">=</span> <span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">local_proxy</span><span class="p">()</span>&#x000A;<span class="n">proxy</span><span class="p">.</span><span class="n">indent</span> <span class="o">=</span> <span class="mi">5</span>&#x000A;<span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">indent</span> <span class="c1">-- =&gt; 2</span>&#x000A;<span class="n">proxy</span><span class="p">.</span><span class="n">indent</span> <span class="c1">-- =&gt; 5</span>&#x000A;</pre>&#x000A;<p>Proxy objects offers one additional feature in addition to the above; the&#x000A;possibility of chaining to a different configuration object other than the&#x000A;global howl.config module. Using the <code>chain_to</code> method, it&rsquo;s possible to create&#x000A;hierarchies of configuration objects (as is done in Howl for modes and buffers):</p>&#x000A;<pre class="highlight lua"><span class="n">proxy</span> <span class="o">=</span> <span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">local_proxy</span><span class="p">()</span>&#x000A;<span class="n">next_proxy</span> <span class="o">=</span> <span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">local_proxy</span><span class="p">()</span>&#x000A;<span class="n">next_proxy</span><span class="p">.</span><span class="n">chain_to</span><span class="p">(</span><span class="n">proxy</span><span class="p">)</span>&#x000A;</pre>&#x000A;<p>In the above example, <code>proxy</code> would defer any lookups not set locally to the&#x000A;global howl.config module, and <code>next_proxy</code> would defer any lookups to <code>proxy</code>.&#x000A;Proxies work against the global configuration variable definitions, and respects&#x000A;any validations, conversions, etc., specified.</p>&#x000A;&#x000A;<h3 id="set">set <span class="arg-list">(name, value)</span></h3>&#x000A;&#x000A;<p>Globally sets the value of the configuration variable with name <code>name</code> to be&#x000A;<code>value</code>. An error is raised for any of the following scenarios:</p>&#x000A;&#x000A;<ul>&#x000A;<li>There exists no known variable with name <code>name</code></li>&#x000A;<li><code>value</code> is not a valid value for the parameter</li>&#x000A;<li>The parameter was defined with the scope &ldquo;local&rdquo;</li>&#x000A;</ul>&#x000A;&#x000A;<p>Upon a successful change, any listeners are notified. To remove any previously&#x000A;set value, pass <code>nil</code> as <code>value</code>. While setting a variable using <code>set</code> is&#x000A;perfectly fine, note that the idiomatic way of setting variables globally is to&#x000A;just assign to the variable name in the config module, like so:</p>&#x000A;<pre class="highlight lua"><span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">my_variable</span> <span class="o">=</span> <span class="kc">true</span>&#x000A;</pre>&#x000A;<h3 id="watch">watch <span class="arg-list">(name, callback)</span></h3>&#x000A;&#x000A;<p>Registers a listener for the variable named <code>name</code>. <code>callback</code>, which must be&#x000A;callable, will be invoked whenever the specified variable has a new value set.&#x000A;<code>callback</code> will be invoked with three parameters:</p>&#x000A;&#x000A;<p><em>name</em> - The name of the parameter being set&#x000A;<em>value</em> - The new value of the parameter&#x000A;<em>is_local</em> - A boolean indicating whether the value was set locally or globally.</p>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2016
            <a class='alert-link' href='https://github.com/howl-editor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
